/*
 * Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
/*
 * Copyright 2000-2002,2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.sun.org.apache.xerces.internal.xni.grammars;

import com.sun.org.apache.xerces.internal.xni.parser.XMLConfigurationException;
import com.sun.org.apache.xerces.internal.xni.parser.XMLErrorHandler;
import com.sun.org.apache.xerces.internal.xni.parser.XMLEntityResolver;
import com.sun.org.apache.xerces.internal.xni.parser.XMLInputSource;
import com.sun.org.apache.xerces.internal.xni.XNIException;

import java.io.IOException;
import java.util.Locale;

/**
 * The intention of this interface is to provide a generic means
 * by which Grammar objects may be created without parsing instance
 * documents.  Implementations of this interface will know how to load
 * specific types of grammars (e.g., DTD's or schemas); a wrapper
 * will be provided for user applications to interact with these implementations.
 *
 * @author Neil Graham, IBM
 */

public interface XMLGrammarLoader {

  /**
   * Returns a list of feature identifiers that are recognized by
   * this XMLGrammarLoader.  This method may return null if no features
   * are recognized.
   */
  public String[] getRecognizedFeatures();

  /**
   * Returns the state of a feature.
   *
   * @param featureId The feature identifier.
   * @throws XMLConfigurationException Thrown on configuration error.
   */
  public boolean getFeature(String featureId)
      throws XMLConfigurationException;

  /**
   * Sets the state of a feature.
   *
   * @param featureId The feature identifier.
   * @param state The state of the feature.
   * @throws XMLConfigurationException Thrown when a feature is not recognized or cannot be set.
   */
  public void setFeature(String featureId,
      boolean state) throws XMLConfigurationException;

  /**
   * Returns a list of property identifiers that are recognized by
   * this XMLGrammarLoader.  This method may return null if no properties
   * are recognized.
   */
  public String[] getRecognizedProperties();

  /**
   * Returns the state of a property.
   *
   * @param propertyId The property identifier.
   * @throws XMLConfigurationException Thrown on configuration error.
   */
  public Object getProperty(String propertyId)
      throws XMLConfigurationException;

  /**
   * Sets the state of a property.
   *
   * @param propertyId The property identifier.
   * @param state The state of the property.
   * @throws XMLConfigurationException Thrown when a property is not recognized or cannot be set.
   */
  public void setProperty(String propertyId,
      Object state) throws XMLConfigurationException;

  /**
   * Set the locale to use for messages.
   *
   * @param locale The locale object to use for localization of messages.
   * @throws XNIException Thrown if the parser does not support the specified locale.
   */
  public void setLocale(Locale locale);

  /**
   * Return the Locale the XMLGrammarLoader is using.
   */
  public Locale getLocale();

  /**
   * Sets the error handler.
   *
   * @param errorHandler The error handler.
   */
  public void setErrorHandler(XMLErrorHandler errorHandler);

  /**
   * Returns the registered error handler.
   */
  public XMLErrorHandler getErrorHandler();

  /**
   * Sets the entity resolver.
   *
   * @param entityResolver The new entity resolver.
   */
  public void setEntityResolver(XMLEntityResolver entityResolver);

  /**
   * Returns the registered entity resolver.
   */
  public XMLEntityResolver getEntityResolver();

  /**
   * Returns a Grammar object by parsing the contents of the
   * entity pointed to by source.
   *
   * @param source the location of the entity which forms the starting point of the grammar to be
   * constructed.
   * @throws IOException When a problem is encountered reading the entity XNIException    When a
   * condition arises (such as a FatalError) that requires parsing of the entity be terminated.
   */
  public Grammar loadGrammar(XMLInputSource source)
      throws IOException, XNIException;
} // XMLGrammarLoader
